Document the tree DND API.

Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>

	* gtk/gtktreednd.c:
	* gtk/gtktreeview.c: Document the tree DND API.

	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source):
	Call gtk_drag_source_unset().

diff --git a/ChangeLog b/ChangeLog
index b165aad97de5a9372d44ebffbeda3ce98e8d3a00..ed09d8a7f2f86a8ce2b559c66f6ef672a8fe980a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/gtktreednd.c: 
+       * gtk/gtktreeview.c: Document the tree DND API.
+
+       * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+       Call gtk_drag_source_unset().  
+       
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index b165aad97de5a9372d44ebffbeda3ce98e8d3a00..ed09d8a7f2f86a8ce2b559c66f6ef672a8fe980a 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/gtktreednd.c: 
+       * gtk/gtktreeview.c: Document the tree DND API.
+
+       * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+       Call gtk_drag_source_unset().  
+       
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index b165aad97de5a9372d44ebffbeda3ce98e8d3a00..ed09d8a7f2f86a8ce2b559c66f6ef672a8fe980a 100644 (file)
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/gtktreednd.c: 
+       * gtk/gtktreeview.c: Document the tree DND API.
+
+       * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+       Call gtk_drag_source_unset().  
+       
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index b165aad97de5a9372d44ebffbeda3ce98e8d3a00..ed09d8a7f2f86a8ce2b559c66f6ef672a8fe980a 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/gtktreednd.c: 
+       * gtk/gtktreeview.c: Document the tree DND API.
+
+       * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+       Call gtk_drag_source_unset().  
+       
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index b165aad97de5a9372d44ebffbeda3ce98e8d3a00..ed09d8a7f2f86a8ce2b559c66f6ef672a8fe980a 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/gtktreednd.c: 
+       * gtk/gtktreeview.c: Document the tree DND API.
+
+       * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+       Call gtk_drag_source_unset().  
+       
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index c1eb4c13c159ef985e3084c19d1bb5cee42a5567..59113ab26ba2fd2f800fac7e03f79db0e21540b1 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+Sun Feb 15 02:46:53 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * gtk/tmpl/gtktreednd.sgml: Add docs.
+
 Sat Feb 14 03:09:49 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtk-sections.txt: Remove duplicated section for

diff --git a/docs/reference/gtk/tmpl/gtktreednd.sgml b/docs/reference/gtk/tmpl/gtktreednd.sgml
index 9414655b6bcbb17e4124a0f222c3bfb3655d4963..9c244f5312367ef86d126b0ec01a6e13c67b24d8 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktreednd.sgml
+++ b/docs/reference/gtk/tmpl/gtktreednd.sgml
@@ -2,27 +2,82 @@
 GtkTreeView drag-and-drop
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Interfaces for drag-and-drop support in GtkTreeView
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level 
+API.
+</para>
+<para>
+The low-level API consists of the GTK+ DND API, augmented by some treeview 
+utility functions: gtk_tree_view_set_drag_dest_row(),
+gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), 
+gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and
+gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but
+nothing is done automatically, and implementing advanced features like
+hover-to-open-rows or autoscrolling on top of this API is a lot of work.
+</para>
+<para>
+On the other hand, if you write to the high-level API, then all the 
+bookkeeping of rows is done for you, as well as things like hover-to-open 
+and auto-scroll, but your models have to implement the 
+#GtkTreeDragSource and #GtkTreeDragDest interfaces.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
 
 </para>
 
+<!-- ##### STRUCT GtkTreeDragSource ##### -->
+<para>
 
-<!-- ##### SECTION See_Also ##### -->
+</para>
+
+
+<!-- ##### STRUCT GtkTreeDragSourceIface ##### -->
 <para>
 
 </para>
 
+@g_iface: 
+@row_draggable: 
+@drag_data_get: 
+@drag_data_delete: 
 
-<!-- ##### STRUCT GtkTreeDragDest ##### -->
+<!-- ##### FUNCTION gtk_tree_drag_source_drag_data_delete ##### -->
 <para>
 
 </para>
 
+@drag_source: 
+@path: 
+@Returns: 
 
-<!-- ##### STRUCT GtkTreeDragSource ##### -->
+
+<!-- ##### FUNCTION gtk_tree_drag_source_drag_data_get ##### -->
+<para>
+
+</para>
+
+@drag_source: 
+@path: 
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_drag_source_row_draggable ##### -->
+<para>
+
+</para>
+
+@drag_source: 
+@path: 
+@Returns: 
+
+
+<!-- ##### STRUCT GtkTreeDragDest ##### -->
 <para>
 
 </para>
@@ -37,13 +92,47 @@ GtkTreeView drag-and-drop
 @drag_data_received: 
 @row_drop_possible: 
 
-<!-- ##### STRUCT GtkTreeDragSourceIface ##### -->
+<!-- ##### FUNCTION gtk_tree_drag_dest_drag_data_received ##### -->
 <para>
 
 </para>
 
-@g_iface: 
-@row_draggable: 
-@drag_data_get: 
-@drag_data_delete: 
+@drag_dest: 
+@dest: 
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_drag_dest_row_drop_possible ##### -->
+<para>
+
+</para>
+
+@drag_dest: 
+@dest_path: 
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_set_row_drag_data ##### -->
+<para>
+
+</para>
+
+@selection_data: 
+@tree_model: 
+@path: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_get_row_drag_data ##### -->
+<para>
+
+</para>
+
+@selection_data: 
+@tree_model: 
+@path: 
+@Returns: 
+
 

diff --git a/gtk/gtktreednd.c b/gtk/gtktreednd.c
index 0af3d0026741ed013c71cfea3784b465ae3c7f4b..e99bc617b4abcc2b94a7450114a390e48dd75cc8 100644 (file)
--- a/gtk/gtktreednd.c
+++ b/gtk/gtktreednd.c
@@ -186,7 +186,7 @@ gtk_tree_drag_dest_drag_data_received (GtkTreeDragDest  *drag_dest,
 
 
 /**
- * gtk_tree_drag_dest_drop_possible:
+ * gtk_tree_drag_dest_row_drop_possible:
  * @drag_dest: a #GtkTreeDragDest
  * @dest_path: destination row
  * @selection_data: the data being dragged

diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 240fa36caa36a099a9cbe586ee5433abffa8d044..18f6a1c2c3784de7002d88da97c92d453289647b 100644 (file)
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -10914,6 +10914,17 @@ unset_reorderable (GtkTreeView *tree_view)
     }
 }
 
+/**
+ * gtk_tree_view_enable_model_drag_source:
+ * @tree_view: a #GtkTreeView
+ * @start_button_mask: Mask of allowed buttons to start drag
+ * @targets: the table of targets that the drag will support
+ * @n_targets: the number of items in @targets
+ * @actions: the bitmask of possible actions for a drag from this
+ *    widget
+ * 
+ * Turns @tree_view into a drag source for automatic DND.
+ **/
 void
 gtk_tree_view_enable_model_drag_source (GtkTreeView              *tree_view,
                                        GdkModifierType           start_button_mask,
@@ -10943,6 +10954,16 @@ gtk_tree_view_enable_model_drag_source (GtkTreeView              *tree_view,
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_enable_model_drag_dest:
+ * @tree_view: a #GtkTreeView
+ * @targets: the table of targets that the drag will support
+ * @n_targets: the number of items in @targets
+ * @actions: the bitmask of possible actions for a drag from this
+ *    widget
+ * 
+ * Turns @tree_view into a drop destination for automatic DND.
+ **/
 void
 gtk_tree_view_enable_model_drag_dest (GtkTreeView              *tree_view,
                                      const GtkTargetEntry     *targets,
@@ -10970,6 +10991,12 @@ gtk_tree_view_enable_model_drag_dest (GtkTreeView              *tree_view,
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_unset_rows_drag_source:
+ * @tree_view: a #GtkTreeView
+ * 
+ * Undoes the effect of gtk_tree_view_enable_model_drag_source().
+ **/
 void
 gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
 {
@@ -10983,6 +11010,7 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
     {
       if (di->source_set)
         {
+          gtk_drag_source_unset (GTK_WIDGET (tree_view));
           clear_source_info (di);
           di->source_set = FALSE;
         }
@@ -10994,6 +11022,12 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_unset_rows_drag_dest:
+ * @tree_view: a #GtkTreeView
+ * 
+ * Undoes the effect of gtk_tree_view_enable_model_drag_dest().
+ **/
 void
 gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view)
 {
@@ -11019,6 +11053,14 @@ gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view)
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_set_drag_dest_row:
+ * @tree_view: a #GtkTreeView
+ * @path: The path of the row to highlight, or %NULL.
+ * @pos: Specifies whether to drop before, after or into the row
+ * 
+ * Sets the row that is highlighted for feedback.
+ **/
 void
 gtk_tree_view_set_drag_dest_row (GtkTreeView            *tree_view,
                                  GtkTreePath            *path,
@@ -11089,6 +11131,14 @@ gtk_tree_view_set_drag_dest_row (GtkTreeView            *tree_view,
     }
 }
 
+/**
+ * gtk_tree_view_get_drag_dest_row:
+ * @tree_view: a #GtkTreeView
+ * @path: Return location for the path of the highlighted row, or %NULL.
+ * @pos: Return location for the drop position, or %NULL
+ * 
+ * Gets information about the row that is highlighted for feedback.
+ **/
 void
 gtk_tree_view_get_drag_dest_row (GtkTreeView              *tree_view,
                                  GtkTreePath             **path,
@@ -11113,6 +11163,18 @@ gtk_tree_view_get_drag_dest_row (GtkTreeView              *tree_view,
     *pos = tree_view->priv->drag_dest_pos;
 }
 
+/**
+ * gtk_tree_view_get_dest_row_at_pos:
+ * @tree_view: a #GtkTreeView
+ * @drag_x: the position to determine the destination row for
+ * @drag_y: the position to determine the destination row for
+ * @path: Return location for the path of the highlighted row, or %NULL.
+ * @pos: Return location for the drop position, or %NULL
+ * 
+ * Determines the destination row for a given position.
+ * 
+ * Return value: whether there is a row at the given postiion,
+ **/
 gboolean
 gtk_tree_view_get_dest_row_at_pos (GtkTreeView             *tree_view,
                                    gint                     drag_x,